include/FLAC++/metadata.h Source File

00001 /* libFLAC++ - Free Lossless Audio Codec library
00002  * Copyright (C) 2002,2003  Josh Coalson
00003  *
00004  * This library is free software; you can redistribute it and/or
00005  * modify it under the terms of the GNU Library General Public
00006  * License as published by the Free Software Foundation; either
00007  * version 2 of the License, or (at your option) any later version.
00008  *
00009  * This library is distributed in the hope that it will be useful,
00010  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00011  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00012  * Library General Public License for more details.
00013  *
00014  * You should have received a copy of the GNU Library General Public
00015  * License along with this library; if not, write to the
00016  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
00017  * Boston, MA  02111-1307, USA.
00018  */
00019 
00020 #ifndef FLACPP__METADATA_H
00021 #define FLACPP__METADATA_H
00022 
00023 #include "export.h"
00024 
00025 #include "FLAC/metadata.h"
00026 
00027 // ===============================================================
00028 //
00029 //  Full documentation for the metadata interface can be found
00030 //  in the C layer in include/FLAC/metadata.h
00031 //
00032 // ===============================================================
00033 
00059 namespace FLAC {
00060     namespace Metadata {
00061 
00062         // ============================================================
00063         //
00064         //  Metadata objects
00065         //
00066         // ============================================================
00067 
00092         class FLACPP_API Prototype {
00093         protected:
00095 
00098             Prototype(const Prototype &);
00099             Prototype(const ::FLAC__StreamMetadata &);
00100             Prototype(const ::FLAC__StreamMetadata *);
00102 
00113             Prototype(::FLAC__StreamMetadata *object, bool copy);
00114 
00116 
00117             void operator=(const Prototype &);
00118             void operator=(const ::FLAC__StreamMetadata &);
00119             void operator=(const ::FLAC__StreamMetadata *);
00121 
00124             virtual void clear();
00125 
00126             ::FLAC__StreamMetadata *object_;
00127         public:
00130             virtual ~Prototype();
00131 
00133 
00134             inline bool operator==(const Prototype &) const;
00135             inline bool operator==(const ::FLAC__StreamMetadata &) const;
00136             inline bool operator==(const ::FLAC__StreamMetadata *) const;
00138 
00140 
00141             inline bool operator!=(const Prototype &) const;
00142             inline bool operator!=(const ::FLAC__StreamMetadata &) const;
00143             inline bool operator!=(const ::FLAC__StreamMetadata *) const;
00145 
00146             friend class SimpleIterator;
00147             friend class Iterator;
00148 
00153             inline bool is_valid() const;
00154 
00161             bool get_is_last() const;
00162 
00168             ::FLAC__MetadataType get_type() const;
00169 
00179             unsigned get_length() const;
00180 
00187             void set_is_last(bool);
00188         private:
00190             Prototype();
00191 
00192             // These are used only by Iterator
00193             bool is_reference_;
00194             inline void set_reference(bool x) { is_reference_ = x; }
00195         };
00196 
00197         inline bool Prototype::operator==(const Prototype &object) const
00198         { return (bool)::FLAC__metadata_object_is_equal(object_, object.object_); }
00199 
00200         inline bool Prototype::operator==(const ::FLAC__StreamMetadata &object) const
00201         { return (bool)::FLAC__metadata_object_is_equal(object_, &object); }
00202 
00203         inline bool Prototype::operator==(const ::FLAC__StreamMetadata *object) const
00204         { return (bool)::FLAC__metadata_object_is_equal(object_, object); }
00205 
00206         inline bool Prototype::operator!=(const Prototype &object) const
00207         { return !operator==(object); }
00208 
00209         inline bool Prototype::operator!=(const ::FLAC__StreamMetadata &object) const
00210         { return !operator==(object); }
00211 
00212         inline bool Prototype::operator!=(const ::FLAC__StreamMetadata *object) const
00213         { return !operator==(object); }
00214 
00215         inline bool Prototype::is_valid() const
00216         { return 0 != object_; }
00217 
00219         FLACPP_API Prototype *clone(const Prototype *);
00220 
00221 
00225         class FLACPP_API StreamInfo : public Prototype {
00226         public:
00227             StreamInfo();
00228 
00230 
00233             inline StreamInfo(const StreamInfo &object): Prototype(object) { }
00234             inline StreamInfo(const ::FLAC__StreamMetadata &object): Prototype(object) { }
00235             inline StreamInfo(const ::FLAC__StreamMetadata *object): Prototype(object) { }
00237 
00241             inline StreamInfo(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
00242 
00243             ~StreamInfo();
00244 
00246 
00247             inline void operator=(const StreamInfo &object) { Prototype::operator=(object); }
00248             inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
00249             inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
00251 
00253 
00254             inline bool operator==(const StreamInfo &object) const { return Prototype::operator==(object); }
00255             inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
00256             inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
00258 
00260 
00261             inline bool operator!=(const StreamInfo &object) const { return Prototype::operator!=(object); }
00262             inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
00263             inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
00265 
00267 
00268             unsigned get_min_blocksize() const;
00269             unsigned get_max_blocksize() const;
00270             unsigned get_min_framesize() const;
00271             unsigned get_max_framesize() const;
00272             unsigned get_sample_rate() const;
00273             unsigned get_channels() const;
00274             unsigned get_bits_per_sample() const;
00275             FLAC__uint64 get_total_samples() const;
00276             const FLAC__byte *get_md5sum() const;
00277 
00278             void set_min_blocksize(unsigned value);
00279             void set_max_blocksize(unsigned value);
00280             void set_min_framesize(unsigned value);
00281             void set_max_framesize(unsigned value);
00282             void set_sample_rate(unsigned value);
00283             void set_channels(unsigned value);
00284             void set_bits_per_sample(unsigned value);
00285             void set_total_samples(FLAC__uint64 value);
00286             void set_md5sum(const FLAC__byte value[16]);
00288         };
00289 
00293         class FLACPP_API Padding : public Prototype {
00294         public:
00295             Padding();
00296 
00298 
00301             inline Padding(const Padding &object): Prototype(object) { }
00302             inline Padding(const ::FLAC__StreamMetadata &object): Prototype(object) { }
00303             inline Padding(const ::FLAC__StreamMetadata *object): Prototype(object) { }
00305 
00309             inline Padding(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
00310 
00311             ~Padding();
00312 
00314 
00315             inline void operator=(const Padding &object) { Prototype::operator=(object); }
00316             inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
00317             inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
00319 
00321 
00322             inline bool operator==(const Padding &object) const { return Prototype::operator==(object); }
00323             inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
00324             inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
00326 
00328 
00329             inline bool operator!=(const Padding &object) const { return Prototype::operator!=(object); }
00330             inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
00331             inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
00333 
00334             void set_length(unsigned length);
00335         };
00336 
00340         class FLACPP_API Application : public Prototype {
00341         public:
00342             Application();
00343             //
00345             /** Constructs a copy of the given object.  This form
00346              *  always performs a deep copy.
00347              */
00348             inline Application(const Application &object): Prototype(object) { }
00349             inline Application(const ::FLAC__StreamMetadata &object): Prototype(object) { }
00350             inline Application(const ::FLAC__StreamMetadata *object): Prototype(object) { }
00352 
00356             inline Application(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
00357 
00358             ~Application();
00359 
00361 
00362             inline void operator=(const Application &object) { Prototype::operator=(object); }
00363             inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
00364             inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
00366 
00368 
00369             inline bool operator==(const Application &object) const { return Prototype::operator==(object); }
00370             inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
00371             inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
00373 
00375 
00376             inline bool operator!=(const Application &object) const { return Prototype::operator!=(object); }
00377             inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
00378             inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
00380 
00381             const FLAC__byte *get_id() const;
00382             const FLAC__byte *get_data() const;
00383 
00384             void set_id(const FLAC__byte value[4]);
00386             bool set_data(const FLAC__byte *data, unsigned length);
00387             bool set_data(FLAC__byte *data, unsigned length, bool copy);
00388         };
00389 
00393         class FLACPP_API SeekTable : public Prototype {
00394         public:
00395             SeekTable();
00396 
00398 
00401             inline SeekTable(const SeekTable &object): Prototype(object) { }
00402             inline SeekTable(const ::FLAC__StreamMetadata &object): Prototype(object) { }
00403             inline SeekTable(const ::FLAC__StreamMetadata *object): Prototype(object) { }
00405 
00409             inline SeekTable(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
00410 
00411             ~SeekTable();
00412 
00414 
00415             inline void operator=(const SeekTable &object) { Prototype::operator=(object); }
00416             inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
00417             inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
00419 
00421 
00422             inline bool operator==(const SeekTable &object) const { return Prototype::operator==(object); }
00423             inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
00424             inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
00426 
00428 
00429             inline bool operator!=(const SeekTable &object) const { return Prototype::operator!=(object); }
00430             inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
00431             inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
00433 
00434             unsigned get_num_points() const;
00435             ::FLAC__StreamMetadata_SeekPoint get_point(unsigned index) const;
00436 
00438             void set_point(unsigned index, const ::FLAC__StreamMetadata_SeekPoint &point);
00439 
00441             bool insert_point(unsigned index, const ::FLAC__StreamMetadata_SeekPoint &point);
00442 
00444             bool delete_point(unsigned index);
00445 
00447             bool is_legal() const;
00448         };
00449 
00453         class FLACPP_API VorbisComment : public Prototype {
00454         public:
00479             class FLACPP_API Entry {
00480             public:
00481                 Entry();
00482                 Entry(const char *field, unsigned field_length);
00483                 Entry(const char *field_name, const char *field_value, unsigned field_value_length);
00484                 Entry(const Entry &entry);
00485                 void operator=(const Entry &entry);
00486 
00487                 virtual ~Entry();
00488 
00489                 virtual bool is_valid() const;
00490 
00491                 unsigned get_field_length() const;
00492                 unsigned get_field_name_length() const;
00493                 unsigned get_field_value_length() const;
00494 
00495                 ::FLAC__StreamMetadata_VorbisComment_Entry get_entry() const;
00496                 const char *get_field() const;
00497                 const char *get_field_name() const;
00498                 const char *get_field_value() const;
00499 
00500                 bool set_field(const char *field, unsigned field_length);
00501                 bool set_field_name(const char *field_name);
00502                 bool set_field_value(const char *field_value, unsigned field_value_length);
00503             protected:
00504                 bool is_valid_;
00505                 ::FLAC__StreamMetadata_VorbisComment_Entry entry_;
00506                 char *field_name_;
00507                 unsigned field_name_length_;
00508                 char *field_value_;
00509                 unsigned field_value_length_;
00510             private:
00511                 void zero();
00512                 void clear();
00513                 void clear_entry();
00514                 void clear_field_name();
00515                 void clear_field_value();
00516                 void construct(const char *field, unsigned field_length);
00517                 void construct(const char *field_name, const char *field_value, unsigned field_value_length);
00518                 void compose_field();
00519                 void parse_field();
00520             };
00521 
00522             VorbisComment();
00523 
00525 
00528             inline VorbisComment(const VorbisComment &object): Prototype(object) { }
00529             inline VorbisComment(const ::FLAC__StreamMetadata &object): Prototype(object) { }
00530             inline VorbisComment(const ::FLAC__StreamMetadata *object): Prototype(object) { }
00532 
00536             inline VorbisComment(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
00537 
00538             ~VorbisComment();
00539 
00541 
00542             inline void operator=(const VorbisComment &object) { Prototype::operator=(object); }
00543             inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
00544             inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
00546 
00548 
00549             inline bool operator==(const VorbisComment &object) const { return Prototype::operator==(object); }
00550             inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
00551             inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
00553 
00555 
00556             inline bool operator!=(const VorbisComment &object) const { return Prototype::operator!=(object); }
00557             inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
00558             inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
00560 
00561             unsigned get_num_comments() const;
00562             Entry get_vendor_string() const; // only the Entry's field name should be used
00563             Entry get_comment(unsigned index) const;
00564 
00567             bool set_vendor_string(const Entry &entry);
00568 
00570             bool set_comment(unsigned index, const Entry &entry);
00571 
00573             bool insert_comment(unsigned index, const Entry &entry);
00574 
00576             bool delete_comment(unsigned index);
00577         };
00578 
00582         class FLACPP_API CueSheet : public Prototype {
00583         public:
00590             class FLACPP_API Track {
00591             protected:
00592                 ::FLAC__StreamMetadata_CueSheet_Track *object_;
00593             public:
00594                 Track();
00595                 Track(const ::FLAC__StreamMetadata_CueSheet_Track *track);
00596                 Track(const Track &track);
00597                 void operator=(const Track &track);
00598 
00599                 virtual ~Track();
00600 
00601                 virtual bool is_valid() const;
00602 
00603                 inline FLAC__uint64 get_offset() const { return object_->offset; }
00604                 inline FLAC__byte get_number() const { return object_->number; }
00605                 inline const char *get_isrc() const { return object_->isrc; }
00606                 inline unsigned get_type() const { return object_->type; }
00607                 inline bool get_pre_emphasis() const { return object_->pre_emphasis; }
00608 
00609                 inline FLAC__byte get_num_indices() const { return object_->num_indices; }
00610                 ::FLAC__StreamMetadata_CueSheet_Index get_index(unsigned i) const;
00611 
00612                 inline const ::FLAC__StreamMetadata_CueSheet_Track *get_track() const { return object_; }
00613 
00614                 inline void set_offset(FLAC__uint64 value) { object_->offset = value; }
00615                 inline void set_number(FLAC__byte value) { object_->number = value; }
00616                 void set_isrc(const char value[12]);
00617                 void set_type(unsigned value);
00618                 inline void set_pre_emphasis(bool value) { object_->pre_emphasis = value? 1 : 0; }
00619 
00620                 void set_index(unsigned i, const ::FLAC__StreamMetadata_CueSheet_Index &index);
00621                 //@@@ It's awkward but to insert/delete index points
00622                 //@@@ you must use the routines in the CueSheet class.
00623             };
00624 
00625             CueSheet();
00626 
00628 
00631             inline CueSheet(const CueSheet &object): Prototype(object) { }
00632             inline CueSheet(const ::FLAC__StreamMetadata &object): Prototype(object) { }
00633             inline CueSheet(const ::FLAC__StreamMetadata *object): Prototype(object) { }
00635 
00639             inline CueSheet(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
00640 
00641             ~CueSheet();
00642 
00644 
00645             inline void operator=(const CueSheet &object) { Prototype::operator=(object); }
00646             inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
00647             inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
00649 
00651 
00652             inline bool operator==(const CueSheet &object) const { return Prototype::operator==(object); }
00653             inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
00654             inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
00656 
00658 
00659             inline bool operator!=(const CueSheet &object) const { return Prototype::operator!=(object); }
00660             inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
00661             inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
00663 
00664             const char *get_media_catalog_number() const;
00665             FLAC__uint64 get_lead_in() const;
00666             bool get_is_cd() const;
00667 
00668             unsigned get_num_tracks() const;
00669             Track get_track(unsigned i) const;
00670 
00671             void set_media_catalog_number(const char value[128]);
00672             void set_lead_in(FLAC__uint64 value);
00673             void set_is_cd(bool value);
00674 
00675             void set_index(unsigned track_num, unsigned index_num, const ::FLAC__StreamMetadata_CueSheet_Index &index);
00676 
00678             bool insert_index(unsigned track_num, unsigned index_num, const ::FLAC__StreamMetadata_CueSheet_Index &index);
00679 
00681             bool delete_index(unsigned track_num, unsigned index_num);
00682 
00684             bool set_track(unsigned i, const Track &track);
00685 
00687             bool insert_track(unsigned i, const Track &track);
00688 
00690             bool delete_track(unsigned i);
00691 
00693             bool is_legal(bool check_cd_da_subset = false, const char **violation = 0) const;
00694         };
00695 
00701         class FLACPP_API Unknown : public Prototype {
00702         public:
00703             Unknown();
00704             //
00706             /** Constructs a copy of the given object.  This form
00707              *  always performs a deep copy.
00708              */
00709             inline Unknown(const Unknown &object): Prototype(object) { }
00710             inline Unknown(const ::FLAC__StreamMetadata &object): Prototype(object) { }
00711             inline Unknown(const ::FLAC__StreamMetadata *object): Prototype(object) { }
00713 
00717             inline Unknown(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
00718 
00719             ~Unknown();
00720 
00722 
00723             inline void operator=(const Unknown &object) { Prototype::operator=(object); }
00724             inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
00725             inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
00727 
00729 
00730             inline bool operator==(const Unknown &object) const { return Prototype::operator==(object); }
00731             inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
00732             inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
00734 
00736 
00737             inline bool operator!=(const Unknown &object) const { return Prototype::operator!=(object); }
00738             inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
00739             inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
00741 
00742             const FLAC__byte *get_data() const;
00743 
00745             bool set_data(const FLAC__byte *data, unsigned length);
00746             bool set_data(FLAC__byte *data, unsigned length, bool copy);
00747         };
00748 
00749         /* \} */
00750 
00751 
00764 
00765         FLACPP_API bool get_streaminfo(const char *filename, StreamInfo &streaminfo);
00766 
00767         /* \} */
00768 
00769 
00802         class FLACPP_API SimpleIterator {
00803         public:
00804             class FLACPP_API Status {
00805             public:
00806                 inline Status(::FLAC__Metadata_SimpleIteratorStatus status): status_(status) { }
00807                 inline operator ::FLAC__Metadata_SimpleIteratorStatus() const { return status_; }
00808                 inline const char *as_cstring() const { return ::FLAC__Metadata_SimpleIteratorStatusString[status_]; }
00809             protected:
00810                 ::FLAC__Metadata_SimpleIteratorStatus status_;
00811             };
00812 
00813             SimpleIterator();
00814             virtual ~SimpleIterator();
00815 
00816             bool init(const char *filename, bool read_only, bool preserve_file_stats);
00817 
00818             bool is_valid() const;
00819             Status status();
00820             bool is_writable() const;
00821 
00822             bool next();
00823             bool prev();
00824 
00825             ::FLAC__MetadataType get_block_type() const;
00826             Prototype *get_block();
00827             bool set_block(Prototype *block, bool use_padding = true);
00828             bool insert_block_after(Prototype *block, bool use_padding = true);
00829             bool delete_block(bool use_padding = true);
00830 
00831         protected:
00832             ::FLAC__Metadata_SimpleIterator *iterator_;
00833             void clear();
00834         };
00835 
00836         /* \} */
00837 
00838 
00879         class FLACPP_API Chain {
00880         public:
00881             class FLACPP_API Status {
00882             public:
00883                 inline Status(::FLAC__Metadata_ChainStatus status): status_(status) { }
00884                 inline operator ::FLAC__Metadata_ChainStatus() const { return status_; }
00885                 inline const char *as_cstring() const { return ::FLAC__Metadata_ChainStatusString[status_]; }
00886             protected:
00887                 ::FLAC__Metadata_ChainStatus status_;
00888             };
00889 
00890             Chain();
00891             virtual ~Chain();
00892 
00893             friend class Iterator;
00894 
00895             bool is_valid() const;
00896             Status status();
00897 
00898             bool read(const char *filename);
00899             bool write(bool use_padding = true, bool preserve_file_stats = false);
00900 
00901             void merge_padding();
00902             void sort_padding();
00903 
00904         protected:
00905             ::FLAC__Metadata_Chain *chain_;
00906             virtual void clear();
00907         };
00908 
00912         class FLACPP_API Iterator {
00913         public:
00914             Iterator();
00915             virtual ~Iterator();
00916 
00917             bool is_valid() const;
00918 
00919             void init(Chain &chain);
00920 
00921             bool next();
00922             bool prev();
00923 
00924             ::FLAC__MetadataType get_block_type() const;
00925             Prototype *get_block();
00926             bool set_block(Prototype *block);
00927             bool delete_block(bool replace_with_padding);
00928             bool insert_block_before(Prototype *block);
00929             bool insert_block_after(Prototype *block);
00930 
00931         protected:
00932             ::FLAC__Metadata_Iterator *iterator_;
00933             virtual void clear();
00934         };
00935 
00936         /* \} */
00937 
00938     };
00939 };
00940 
00941 #endif